How to document Diffpack applications

Follow these steps:

• Give a name to your software. Below we use NAME as the name of the software. For example, if you have made a C++ class (which may be a simulator) then NAME can be taken as the name of that class. Otherwise, find some suitable one-word name!

• Make a directory structure containing the source code, the LaTeX documentation and the World Wide Web information. This is accomplished by the Diffpack script Mkdpdoc. Just type Mkdpdoc NAME on the command line. The script will make these subdirectories in the current working directory: NAME/src for the source code, NAME/doc for LaTeX documentation and NAME/www for WWW documentation. Moreover, template files are copied to these subdirectories. The rest of the steps will be to edit the files that the script has copied.

• Invoke the NAME/www/index.html by some WWW browser, for example, netscape or Mosaic. Also load this file into an editor. Read the text in the browser window and make changes with the editor. The most common changes are listed below.

• The Mkdpdoc script assumes that you have only a header file and a C++ file, where the main part of the file name is the same as NAME. This may not be the case so you should assure that all your source files are listed with correct links.

• Take a look at the NAME/doc/NAME.ps file. This is a PostScript version of the LaTeX template file NAME/doc/NAME.ctex which you must fill with equations, software design, user examples etc. Load the NAME.ctex into an editor and adapt the text to your problem. Note that the extension of this file is .ctex and not .tex. The reason is that source code should be copied into this file and we use the special Diffpack LaTeX command @@@CODE etc for doing this (see the appendix in NAME.ctex) such that always the most recent version of the source code is included in the document. The script pretex converts the NAME.ctex file into an ordinary NAME.tex LaTeX file.

• When the text in the NAME.ctex file is okay, type pretex NAME to convert the NAME.ctex file to NAME.tex where all the source code is copied into the LaTeX file using a verbatim environment. Run latex and dvips to produce a PostScript file NAME.ps.

• Make further changes in the NAME/www/index.html file: Your name must be filled in together with a link to your WWW home page, you can choose a logo for your institution and the email address at the bottom of the page must be correct.

• Reload the index.html file and test all hyperlinks.

• Move the NAME directory tree to a suitable location, f.ex. let it be a subdirectory of your ~/www_docs directory. If you do not have a World Wide Web home page, you can run the script MkWWWhome.sh and answer the questions about your name, position, telephone number etc. The script will make a ~/www_docs directory and show you the resulting home page in Mosaic. After you have moved the NAME tree to a subdirectory under ~/www_docs, take a Chmod ~/www_docs to open the subdirectories and files for reading. Thereafter send the URL to your ~/www_docs/NAME/www/index.html file to dp-submit@si.sintef.no. Your WWW page for this software will then be accessible from the Diffpack home page such that other users can see what kind of software you have made (if you do not want public access to your WWW page, add a password or let us know).